# data_input_parser.py
"""模块：用于从标准输入解析不同格式的可变数据。"""

import sys
from typing import List, TextIO


def read_string_input(input_stream: TextIO = sys.stdin) -> str:
    """
    从输入流读取并返回第一行字符串（去除首尾空白）。

    Args:
        input_stream (TextIO): 输入流对象，默认为 sys.stdin。

    Returns:
        str: 解析后的字符串。
    """
    return input_stream.readline().strip()


def read_numeric_matrix(input_stream: TextIO = sys.stdin) -> List[List[int]]:
    """
    从输入流读取多行纯数字矩阵。
    读取所有剩余的行，每行按空格分割成整数。

    Args:
        input_stream (TextIO): 输入流对象，默认为 sys.stdin。

    Returns:
        List[List[int]]: 解析后的二维整数列表（矩阵）。
    """
    matrix = []
    for line in input_stream:
        stripped_line = line.strip()
        if stripped_line:
            numbers = [int(num) for num in stripped_line.split()]
            matrix.append(numbers)
    return matrix


def read_char_matrix_with_header(input_stream: TextIO = sys.stdin) -> List[List[str]]:
    """
    从输入流读取带行列头的字符矩阵。
    第一行包含两个整数 R (行数) 和 C (列数)，用空格分隔。
    接下来的 R 行，每行包含 C 个由单个空格分隔的字符。

    Args:
        input_stream (TextIO): 输入流对象，默认为 sys.stdin。

    Returns:
        List[List[str]]: 解析后的二维字符列表（矩阵）。

    Raises:
        ValueError: 如果输入格式不正确。
    """
    header_line = input_stream.readline().strip()
    if not header_line:
        raise ValueError("Input stream is empty or header line is missing.")

    try:
        rows, cols = map(int, header_line.split())
    except ValueError:
        raise ValueError("First line must contain two integers: rows and columns.")

    if rows <= 0 or cols <= 0:
        raise ValueError("Number of rows and columns must be positive integers.")

    matrix = []
    for i in range(rows):
        line = input_stream.readline()
        if not line:
            raise ValueError(f"Expected {rows} rows of data, but input ended early.")
        parts = line.strip().split()
        if len(parts) != cols:
            raise ValueError(
                f"Row {i + 1} declared {cols} columns, but found {len(parts)} elements."
            )
        matrix.append(parts)

    return matrix
